"""
OAuth 2.0 客户端验证器接口定义
"""
from abc import ABC, abstractmethod

from pydantic import BaseModel, Field


class ClientInfo(BaseModel):
    """
    用于在服务内部传递已验证的客户端信息的标准模型。
    """
    client_id: str = Field(..., description="客户端ID")
    client_name: str = Field(..., description="客户端名称")
    grant_types: list[str] = Field(default_factory=list, description="该客户端允许使用的授权类型列表")
    redirect_uris: list[str] = Field(default_factory=list, description="该客户端注册的回调URI列表")
    scope: str | None = Field(default=None, description="该客户端被允许申请的完整权限范围 (空格分隔)")


class BaseClientVerifier(ABC):
    """
    客户端验证器服务的抽象基类。
    所有具体的客户端验证器实现都应继承此类。
    """

    @abstractmethod
    async def verify_by_id(self, client_id: str, redirect_uri: str | None = None) -> ClientInfo:
        """
        根据客户端ID验证客户端是否存在、是否启用。
        如果提供了 redirect_uri，则必须一并验证它是否在客户端的允许列表中。
        验证失败时应抛出 InvalidClientError 或其子类异常。

        Args:
            client_id: 要验证的客户端ID。
            redirect_uri: (可选) 在授权码流程中必须提供，用于校验回调地址。

        Returns:
            一个包含客户端详细信息的 ClientInfo 对象。
        
        Raises:
            InvalidClientError: 如果客户端未找到、被禁用，或 redirect_uri 不匹配。
        """
        pass

# 为保持兼容性，暂时保留别名
ClientVerifier = BaseClientVerifier
